eDocs Home > BEA AquaLogic Data Services Platform 3.0 Documentation > Data Services Developer's Guide

Understanding Data Service Annotations

This section describes the syntax and semantics of annotations in data service documents developed within ALDSP's Data Services Studio. Data service documents define collections of XQuery functions and/or XQSE functions or procedures. Annotations are XML fragments comprising the character content of XQuery pragmas.

There are two types of annotations:

• Global annotations. These pertain to the entire entity or library data service document. Global annotations are also referred to as XDS or XFL annotations respectively.
• Local annotations. These pertain to a particular function. Local annotations are also referred to as function annotations.

Topics 

See also: Data Service Annotations Schema

XDS Annotations

There is a single XDS ("XQuery Data Service") annotation per entity data service document, which appears before all function annotations. The identifier for the pragma carrying the XDS annotation is xds. The qualified name of the top level element of the XML fragment corresponding to an XDS annotation has the local name xds and the namespace URI:

urn:annotations.ld.bea.com

Each entity data service is associated with a unique target type. The prime type of the return type of every read function must match its target type. The target type of an entity data service is an element type whose qualified name is specified by the targetType attribute of the xds element. It is defined in a schema file associated with the entity data service.

The contents of the top-level xds element is a sequence of the following blocks of properties:

• General Properties
• Data Access Properties
• Target Type Properties
• Key Properties
• Relationship Properties
• Update Properties
• Security Properties

The following excerpt provides an example of an XDS annotation. In this case, the target type t:CUSTOMER associates the entity data service with a t:CUSTOMER type in a schema file.

(::pragma xds <x:xds xmlns:x="urn:annotations.ld.bea.com" targetType="t:CUSTOMER" xmlns:t="ld:oracleDS/CUSTOMER">

<author>Joe Public</author>
<relationalDB name="OracleDS"/>

<field type="xs:string" xpath="FIRST_NAME">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="FIRST_NAME"/>
		<properties nullable="false"/>
</field>

<field type="xs:string" xpath="LAST_NAME">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="LAST_NAME"/>
	<properties nullable="false"/>
</field>

<field type="xs:string" xpath="CUSTOMER_ID">
	<extension nativeFractionalDigits="0" nativeSize="64"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="CUSTOMER_ID"/>
	<properties nullable="false" nativeKey="true"/>
</field>

<field type="xs:dateTime" xpath="CUSTOMER_SINCE">
	<extension nativeFractionalDigits="0" nativeSize="7"
		nativeTypeCode="93" nativeType="DATE"
		nativeXpath="CUSTOMER_SINCE"/>
	<properties nullable="false"/>
</field>

<field type="xs:string" xpath="EMAIL_ADDRESS">
	<extension nativeFractionalDigits="0" nativeSize="32"
		nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="EMAIL_ADDRESS"/>
	<properties nullable="false"/>
</field>

<key name="CUSTOMER_ID"/>

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
	XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
	maxOccurs="unbounded" opposite="CUSTOMER"/>
</x:xds>::-)

General Properties

There are two types of general XDS properties:

• Standard Document Properties
• User-Defined Properties

Standard Document Properties

You can specify a set of standard document properties consisting of optional XML elements containing information pertaining to the author, creation date, or version of the document. You can also use the optional element named "documentation" to specify related documentation. The names and types of the elements in the standard document properties block, as well as examples of their use, are shown in the table below.

Standard Document Properties

<author>J. Public</author>

<creationDate>2004-05-31</creationDate>

<version>2.2<version>

<documentation> Models an online Customer </documentation>

User-Defined Properties

In addition to the standard properties, you can specify custom properties pertaining to the entire data service document using a sequence of zero (0) or more "property" elements. Each property element must be named using its "name" attribute and may contain any string content. For example:

<property name="data-refresh-rate">week</property>

Data Access Properties

A data service may be used to model access to an external data source or to model a transformation on top of one or more data sources or other transformations. Data services modeling external data sources are referred to as physical. Transformation data services not representing a particular data source are referred to as logical.

The block of data access properties allows each data service to define whether it is physical or not. When a data service is physical, the data access annotation describes the type of the external source being accessed by its external functions (there may be a single external source per data service) and its connection properties. When a data service is logical, the data service is designated as a user-defined view, and no connection information is required.

The following types of physical data services are supported:

• Relational
• Web service
• Java function
• Delimited content
• XML content

The following sections describe the data access annotation for the physical data service types, as well as for data services that are designated as user-defined views. You can specify only one of these annotations in each data service. If no annotation is provided, the data service is considered a user-defined view.

Relational Data Service Annotations

The data access annotation for a relational data service consists of the element relationalDB with two required attributes, described in the following table:

Required Attributes for the relationalDB Element

<relationalDB name="OracleDS" providerId="Oracle-9"/>

In addition, the relationalDB element can contain the following optional parts:

• An optional element, named "properties", that exposes relational provider-specific attributes, such as the values of specific settings of the Relational Database Management System (RDBMS) represented by the relational source.
• An optional attribute, named sourceBindingProviderClassName, that specifies the transformation used to determine the relational source that should be used at system runtime in the place of the statically defined source.

Source Binding Provider

The value of the optional sourceBindingProviderClassName attribute should be bound to the fully-qualified name of a user-defined Java class implementing the interface:

com.bea.ld.bindings.SourceBindingProvider

defined by the following:

package com.bea.ld.bindings;
public interface SourceBindingProvider
{
	public String getBinding(String genericLocator, boolean isUpdate);
}

The user-defined implementation should provide the transformation that, given the statically configured relational source name (parameter genericLocator) and a Boolean flag indicating whether the relational source is accessed in query or update mode (parameter isUpdate), determines the name of the relational source name used by the system at runtime.

You can use this transformation mechanism to perform credential mapping. In this case, a single set of query or update operations to be performed in the name of two distinct users U1 and U2 against the same statically-configured relational source R0, is executed against two distinct relational sources R1 and R2 respectively (where all sources R0, R1, R2 represent the same RDBMS and the security policies applied to the connection credentials used for R1 and R2 correspond to the security policies applied to the application credentials of user U1 and U2, respectively).

You should set the source binding provider name uniformly across all relational data services sharing the same relational source JNDI name. Although this restriction is not enforced, its violation could result in unpredictable behavior at runtime.

Web Service Data Service Annotations

The data access annotation for a data service based on a Web service consists of the empty element webService with two required attributes, described in the following table:

Required Attributes for the webService Element

Example:

<webService targetNamespace="urn:GoogleSearch"
	wsdl="ld:google/GoogleSearch.wsdl"/>

In addition, if the physical data service models an ALSB proxy service, the webService element can carry the following optional attributes:

Optional Attributes for the webService Element

Java Function Data Service Annotations

The data access annotation for a Java function data service consists of the empty element javaFunction with a single required attribute named class, whose value should be set to the fully qualified name of the Java class serving as the external source.

Example:

<javaFunction class="com.example.Test"/>

Delimited Content Data Service Annotations

The data access annotation for a delimited content data service is the empty element delimitedFile, accepting the optional attributes described in the following table:

Optional Attributes for the delimitedFile Element

Example:

<delimitedFile schema="ld:df/schemas/ALL_TYPES.xsd" hasHeader="true"
	delimiter="," file="ld:df/ALL_TYPES.csv"/>

XML Content Data Service Annotations

The data access annotation for an XML content data service is the empty element xmlFileaccepting the attributes described in the following table:

Attributes for the xmlFile Element

Example:

<xmlFile schema="ld:xml/somewhere/CUSTOMER.xsd"
	file="ld:xml/CUSTOMER_NESTED.xml"/>

User Defined View XDS Annotations

The data access annotation for a user-defined view data service is also known as a logical data service. It consists of the single empty element:

userDefinedView

Example:

<userDefinedView/>

Target Type Properties

The optional block of target type properties enables you to annotate simple valued fields in the target type of the entity data service with native type information pertaining to the following:

• The type of the corresponding field in the underlying external source (applicable only to data source data services)
• Information about the field's properties with respect to its update behavior. Each annotated field is represented by the element named "field"with two required attributes, described in the following table:

Required Attributes for the field Element

The following excerpt provides an example of a field element definition:

<field type="xs:string" xpath="FIRST_NAME">
	<extension nativeSize="64" nativeTypeCode="12" nativeType="VARCHAR2"
		nativeXpath="FIRST_NAME"/>
	<properties nullable="false"/>
</field>

Native Type Properties

Each "field" element can contain an optional "extension" element that accepts the optional attributes described in the following table:

Optional Attributes for the extension Element

Update-related Type Properties

Each "field" element can also contain an optional "properties" element that accepts the optional attributes described in the following table:

properties Element Optional Attributes

Key Properties

The optional block of key properties enables you to specify an identity constraint (key) on the entity data service target type. An identity constraint for an entity data service is represented by the element "key" along with an XML schema specifying the key type.

The "key" element accepts a required attribute "type", whose value should be bound to the qualified name of the element type defining the locations of the data fields comprising the key. The key type should in turn be specified by an XML schema imported by the data service. 

The "key" element may also carry the following optional attributes: 

key Element Optional Attributes

In most cases, the identity constraint refers to the collection of data bindings returned by the entity data service's read functions, with each binding's type being the data service target type. In the case that a data service returns an XML document, the collection on which the identity constraint may be specified is normally defined by some element nested within the document element. In such a case, the "key" element contains an optional "selector" element that is used to specify the collection. The "selector" element carries a required "xpath" attribute, whose value is an XPath value pointing to the nested element defining the collection root. The XPath forms accepted by this attribute are simplified XPaths, using only the element or attribute axes and no predicates.

The following excerpt provides an example of a "key" element definition:

<key name="CUSTOMER_ID"/>
	<selector xpath="CUSTOMER"/>
</key>

Relationship Properties

The optional block of relationship properties enables you to specify a set of relationship targets. A relationship target of an entity data service is an entity data service with which first service maintains a unidirectional or bidirectional relationship. Unidirectional relationships are realized through one or more navigatefunctions in the first data service that returns one or more instances of objects of the second service target type. Bidirectional relationships require that reciprocal functions are present in the second data service as well.

A relationship target is represented by the element relationshipTarget that accepts the attributes described in the following table:

Attributes for the relationshipTarget Element

Additionally, the relationshipTarget element can itself contain the element "relationship" which in turn contains the nested element "description" that contains a human readable description about the relationship.

The following excerpt provides an example of a relationshipTarget element definition:

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
	XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
	maxOccurs="unbounded" opposite="CUSTOMER"/>

Update Properties

The optional block of update properties enables you to specify a set of properties that establish certain policies about updating an entity data service's underlying sources. In particular, you can specify the following policies:

• The fields to use for optimistic locking purposes.

Optimistic Locking Fields

SDO update assumes optimistic locking transactional semantics. The data service being updated can specify the fields that should be checked for updates during the interim using the empty element optimisticLockingFields that accepts one of the following as its content:

• An empty element, named updated, to specify only updated fields.
• An empty element, named projected, to specify all projected fields.
• One or more elements, named "field", that accept a required string-valued attribute named name to specify user-specified fields.

The following excerpt provides an example of a functionForDecomposition element definition:

<optimisticLockingFields>
	<updated/>
</optimisticLockingFields>

Security Properties

You can use a data service to define one or more user-defined, logical protected resources.
The element secureResources, containing one or more string-valued elements named secureResource, can be used for this purpose.
For example:

<secureResources>
	<secureResource>MyResource</secureResource/>
	<secureResource>MyOtherResource</secureResource/>
</secureResources>

You can link a logical resource defined using this syntax to a user-provided security policy using the AquaLogic Data Services Console. Query content can inquire about a user's ability to access a logical resource using the built-in function isAccessAllowed().

Function Annotations

There is a single function annotation per data service function or procedure, which appears before the function or procedure declaration in the document. The identifier for the pragma carrying the function annotation is "function". The qualified name of the top level element of the XML fragment corresponding to a function annotation has the local name "function" and the namespace URI urn:annotations.ld.bea.com.

Modeling Kind

Each entity data service function or procedure is classified using one of the following categories:

• Create procedure
• Read function
• Update procedure
• Delete procedure
• Navigate function
• Library function or procedure

The classification of a data service method is determined by the value of the optional attribute "kind" in the function element, which accepts the values create, read, update, delete, navigate, or library to denote the corresponding categories. The default value is library.

Each library data service function or procedure is always of kind library.

The prime type of the return type of a read function must match the target type of the entity data service. In addition, the function element for a navigate function must carry a string-valued attribute returns whose value must match the role name of a relationship target defined in the data service. Moreover, the prime type of the return type of a navigate function must match the target type of the data service serving as the relationship target.

An operation designated as a procedure has in the general case side-effects. In other words, its invocation entails modifications of the state of the affected data sources. Therefore, a procedure may not be referenced by AquaLogic Data Services Platform functions.

A library function residing in a relational database function library data service file is always external. It may not be invoked directly by clients. Instead, it should be referenced by other data service functions or ad-hoc queries.

Visibility

Functions or procedures may also be classified based on their visibility using one of the following categories:

• Public
• Protected
• Private

The classification of a data service method is determined by the value of the optional attribute "visibility" in the function element, which accepts the values public, protected, or private to denote the corresponding categories. The default value is protected.

Public methods are accessible by ALDSP dataspace clients as well as other data services within the dataspace.

Protected methods are not accessible by ALDSP dataspace clients but can be accessed by other data services within the dataspace.

Private methods may be accessed only by other methods within the data service in which they are defined.

Primary

The optional boolean attribute "isPrimary" may also be used to classify entity data service methods as primary or non-primary. The default value is false.

This property is applicable only to create, update and delete procedures or read functions.

In the case of a procedure, when this property is set to true, it denotes that the procedure should be the one to be automatically used by the update maps of logical data services directly depending on the data service defining the procedure, in order to perform the corresponding update operation (i.e. create, update or delete).  

In the case of a read function, when this property is set to true, it denotes that the read function should be the one to be used to infer the data service update map.

There may exist at most one primary method of each kind specified within an entity data service.

URI

Finally, the namespace URIs of the qualified names of all the functions and/or procedures in a data service must specify the location of the data service document in the ALDSP repository. For example:

ld:{directory path to data service folder}/{data service file name without extension}

The function element accepts the additional optional attributes described in the table below:

Optional Attributes for the function Element

The content of the top-level function element is a sequence of the following blocks of properties:

• General Properties
• UI Properties
• Cache Properties
• Transaction Properties
• Behavioral Properties
• Signature Properties
• Native Properties
• Implementation Properties

The following excerpt provides an example of a function annotation:

( ::pragma function
<f:function xmlns:f="urn:annotations.ld.bea.com" kind="read" nativeName="CUSTOMER" nativeLevel2Container="RTL" style="table">
<nonCacheable/>
</f:function>::-)

General Properties

All standard document properties and user-defined properties defined in Standard Document Properties and User-Defined Properties are applicable to function annotations.

UI Properties

A set of user interface properties may be introduced by the XQuery Editor to persist location information about the graphical components representing the expression in the function body. UI properties are represented by the element uiProperties which accepts a sequence of one or more elements, named component, as its content. Each "component" element accepts the attributes described in the following table.

Attributes for the component Element

In addition, each "component" element may optionally contain one or more treeInfo elements containing information about the tree representation of the types pertaining to the component. In the absence of the above property, the query editor uses the default layout.

Cache Properties

You can use the optional block of cache properties to specify whether a function can be cached or not. You should specify a function whose results for the same set of arguments are intrinsically highly volatile as non-cached. On the other hand, you should specify a function whose results for the same set of arguments are either fixed or remain unchanged for a period of time as cacheable.

This property of a function is represented by the empty element nonCacheable. In the absence of the nonCacheable element, a function is considered to be potentially cacheable. The following excerpt provides an example:

<nonCacheable/>

Transaction Properties

You can use the optional block of transaction properties to specify whether a procedure can participate in a transaction or not. This property is applicable only to physical procedures bound to external data sources of type Java or ALSB proxy service. A transactional procedure should rollback its effects if the overall transaction, in which it participates, fails.

This property is represented by the empty element nonTransactional. In the absence of the nonTransactional element, a procedure is considered to be transactional. The following excerpt provides an example:

<nonTransactional/>

Behavioral Properties

The optional block of behavioral properties allows you to provide information related to known associations between a function's input and its output, or across two or more functions. In particular, the user may specify the following:

• Inverse Functions
• Equivalent Transforms

Inverse Functions

Given an XQuery function f, the optional block of inverse functions may be used in order to denote a function g, defined over the range of f, that, when composed with f (i.e. g(f)), renders one of the parameters of f. If f has multiple parameters, an inverse function may be defined for each one of its parameters.

The inverse functions block is represented by an optional element, named inverseFunctions, which accepts as its content a sequence of empty elements, named inverseFunction. Each inverseFunction element accepts the following attributes:
parameterIndex. Optional attribute denoting the index of the parameter for which the inverse function is defined. The index of the first parameter is assumed to be 1. It may be omitted if the function being annotated has a single parameter.

• name. Required attribute denoting the fully-qualified name of the inverse function.
  

  Both the annotated and the inverse function must be either built-in or external XQuery functions.

  The following excerpt provides an example of an inverseFunctions element definition:
  

  <inverseFunctions>
  	<inverseFunction parameterIndex="2" name="p:MyInverse" xmlns:p ="urn:test"/>
  </inverseFunctions>

Equivalent Transforms

Given an XQuery function: f, the optional block of equivalent transforms may be used in order to denote a pair of functions_C_ and C' with identical signatures and equivalent semantics, that accept f as one of their parameters. In simple terms, the equivalence is perceived to mean that each occurrence of C(...,f,...) may be safely substituted with: C'(...,f,...).

The equivalent transforms block is represented by an optional element, named equivalentTransforms, which accepts as its content a sequence of empty elements, named pair. Each pair element accepts the following required attributes:

• source. Denotes the fully qualified name of the source transform (i.e.: C).
• target. Denotes the fully qualified name of the target transform (i.e.: C').
• arity. Denotes the (common) arity of the source and target transforms.
  

  The source transform may be either a built-in or external function. Both source and target transforms must not be defined as invertible functions.

The following excerpt provides an example of an equivalentTransforms element definition:

<equivalentTransforms>
	<pair source="p:sourceFunction_1" target="p:targetFunction_1"   arity="1" xmlns:p ="urn:test1"/>
	<pair source="q:sourceFunction_2" target="q:targetFunction_2"   arity="3" xmlns:q="urn:test2"/>
</equivalentTransforms>

Polymorphic Functions

A library function residing in a relational database function library data service may be designated as polymorphic if its actual return type can be determined from the actual type of one of its parameters. A polymorphic function is annotated by an optional element, named isPolymorphic, which accepts as its content an empty element, named parameter. The parameter element accepts the following optional attribute:

index. Denotes the index of the parameter whose actual type determines the function's actual return type. The index of the first parameter is assumed to be 1. It may be omitted if the function being annotated has a single parameter.

The following excerpt provides an example of an equivalentTransforms element definition:

<sPolymorphic>
	<parameter index = "2"/>
</sPolymorphic>

Signature Properties

You can use the optional block of signature properties to annotate the parameters of a data service function or procedure with additional information to that provided by the function signature. These properties are applicable to physical data service functions or procedures.

The signature properties block is represented by the element params which accepts a sequence of one or more elements, named param, as its content. Each param element is an empty element that accepts the optional attributes described in the following table:

param Element Optional Attributes

The following excerpt provides an example of a params element definition:

<params>
	<param nativeType="java.lang.String"/>
	<param nativeType="java.lang.int"/>
</params>

Native Properties

You can use native properties to further annotate a data source function or procedure based on the type of the external source that it represents. There are two types of native properties pertaining to relational and Web service sources respectively:

• SQL query properties
• SOAP handler properties

SQL Query Properties

The function annotation element of a function that represents a user-defined SQL query has its style attribute set to sqlQuery and accepts a nested element, named "sql". The sql element accepts string content that corresponds to the statement of the (possibly parameterized) SQL query that the function represents.

If required, the statement can be escaped inside a CDATA section to account for reserved XML characters (e.g. <, >, &). The sql element also accepts the optional attribute isSubquery whose boolean value indicates whether the SQL statement may be used as a nested SQL sub-query. If the attribute is absent, its value defaults to true.

The following excerpt provides an example of a sqlQuery element definition:

<sql isSubquery="true">
	SELECT t.FIRST_NAME FROM RTLALL.dbo.CUSTOMER t</sql>

SOAP Handler Properties

The "function" annotation element of a function or procedure that represents a Web service call accepts a nested element, named interceptorConfiguration. The interceptorConfiguration element accepts two required attributes, as described below:

Required Attributes for the interceptorConfiguration Element

Implementation Properties

You can use implementation properties to specify that an external create, update or delete procedure is implemented by the update map of the data service in which it is defined.

The optional element "implementation" accepts the required empty element "updateTemplate" as its content.

The following excerpt provides an example:

<implementation>
	<updateTemplate/>
</implementation>

XFL Annotations

There is a single XFL ("XQuery Function Library") annotation per library data service document, which appears before any function annotation in the document. The identifier for the pragma carrying the XFL annotation is "xfl". The qualified name of the top level element of the XML fragment corresponding to an XFL annotation has the local name:

xfl

and the namespace URI:

urn:annotations.ld.bea.com

The contents of the top-level xfl element is a sequence of the following blocks of properties.

• General Properties
• Data Access Properties

The following sections provide detailed descriptions of each block of properties, while the following excerpt provides an example of a XFL annotation, which may serve as a reference.

(::pragma xfl <x:xfl xmlns:x="urn:annotations.ld.bea.com">
<creationDate>2005-03-09T17:48:58</creationDate>
<webService targetNamespace="urn:GoogleSearch"
	wsdl="ld:google/GoogleSearch.wsdl"/>
</x:xfl>::-)

General Properties

The general properties applicable to an library data service document are identical to the general properties for an entity data service document, as described in General Properties.

Data Access Properties

Each library data service document defines one or more XQuery functions and/or XQSE functions or procedures that serve as library operations that can be used either inside other entiry or library data service documents.

Since library data service documents do not have a target type, the return types of the library functions found inside these document may differ from each other. In particular, a function inside a library data service document may return a value having a simple type (or any other type). Library data service functions can be external data source functions or user-defined.

The following types of library data service documents are supported:

• Relational (physical)
• Web service (physical)
• Java function (physical)
• Relational database function (physical)
• User-defined view (logical)

You can specify only one of the annotations in each library data service. If no annotation is provided, the library data service is considered a user-defined view.

The data access properties for Relational, Web service, Java function, and user-defined view library data service documents are the same as the corresponding properties for entity data service documents, as described above.

A relational database function library data service contains native functions, either database vendor-provided or user-defined in the database, from one or more relational data sources, modeled as external XQuery functions.

The data access annotation for a relational database function library data service comprises an element named customNativeFunctions with a single child element, named relational, whose content is a sequence of one or more elements named dataSource. Each dataSource element contains a single text value, which should be set to the JNDI name by which the external relational source has been registered with the application server.

Here is an example:

<customNativeFunctions>
<relational>
	<dataSource>oracleDS1</dataSource>
	<dataSource>oracleDS2</dataSource>
	</relational>
</customNativeFunctions>

Security Properties

The same as in entity data services. 

Contact BEA | Feedback | Privacy | (c) 2008 BEA Systems